package com.witmore.skyline.web.annotation;

import com.witmore.skyline.web.enums.TimePrecision;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * API缓存注解
 * 用于标识方法是否需要缓存以及缓存策略
 * <p>
 * Author: 豆子高
 * Date: 2025/10/24
 */
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface ApiCache {

    /**
     * 缓存过期时间（分钟）
     * 0 表示不缓存
     * 大于0 表示缓存对应的分钟数
     */
    long expireMinutes() default 0;

    /**
     * 缓存key的参数名称
     * 用于构建缓存key，按照参数顺序拼接
     * 例如: keyParams = {"deviceSn", "startTime", "endTime"}
     * 会根据方法参数值构建类似: "method_name:deviceSn_value:startTime_value:endTime_value" 的key
     */
    String[] keyParams() default {};

    /**
     * 缓存key前缀
     * 如果不指定，默认使用 "方法所在类名:方法名" 作为前缀
     */
    String keyPrefix() default "";

    /**
     * 时间参数名称
     * 指定哪些参数是时间类型，需要进行时间精度处理
     * 例如: timeParams = {"startTime", "endTime"}
     */
    String[] timeParams() default {};

    /**
     * 时间精度
     * 控制时间参数在缓存key中的精度级别
     * 默认为SECOND，即保持原始精度
     */
    TimePrecision timePrecision() default TimePrecision.SECOND;
}
